.\" RCSid "$Id: rhpict.1,v 1.6 2008/11/10 19:08:17 greg Exp $"
.TH RHPICT 1 3/10/99 RADIANCE
.SH NAME
rhpict - render a RADIANCE picture from a holodeck file
.SH SYNOPSIS
.B rhpict
[
.B options
]
.B holodeck
.SH DESCRIPTION
.I Rhpict
generates one or more pictures from the RADIANCE holodeck file
.I holodeck
and sends them to the standard output.
The
.I \-o
option may be used to specify an alternate output file.
Other options specify the viewing parameters and provide
some control over the calculation.
.PP
The view as well as some of the other controls
are shared in common with the
.I rpict(1)
command.
The options that are unique to
.I rhpict
are given first, followed by the more familiar ones.
.TP 10n
.BI -s
Use the smooth resampling algorithm, which amounts to linear interpolation
between ray samples with additional edge detection along color and object
boundaries.
This is the default.
.TP
.BI -r \ rf
Use random resampling, where
.I rf
is a fraction from 0 to 1 indicating the desired degree of randomness.
A random fraction of 0 is not the same as smooth resampling,
because there is no linear interpolation, just Voronoi regions.
Values greater than 1 produce interesting underwater effects.
.TP
.BI -x \ res
Set the maximum x resolution to
.I res.
.TP
.BI -y \ res
Set the maximum y resolution to
.I res.
.TP
.BI -pa \ rat
Set the pixel aspect ratio (height over width) to
.I rat.
Either the x or the y resolution will be reduced so that the pixels have
this ratio for the specified view.
If
.I rat
is zero, then the x and y resolutions will adhere to the given maxima.
.TP
.BI -pe \ expval
Set the exposure value for the output pictures to
.I expval.
Since filtering is performed by
.I rhpict,
there is little sense in passing the output through
.I pfilt(1),
other than changing the exposure.
This option eliminates that need.
The value may be specified either as a multiplier, or as a number
f-stops preceeded by a '+' or '-' character.
.TP
.BI -vt t
Set view type to
.I t.
If
.I t
is 'v', a perspective view is selected.
If
.I t
is 'l', a parallel view is used.
A cylindrical panorma may be selected by setting
.I t
to the letter 'c'.
This view is like a standard perspective vertically, but projected
on a cylinder horizontally (like a soupcan's-eye view).
Three fisheye views are provided as well; 'h' yields a hemispherical fisheye
view, 'a' results in angular fisheye distortion, and 's'
results in a planisphere (stereographic) projection.
A hemispherical fisheye is a projection of the hemisphere onto a circle.
The maximum view angle for this type is 180 degrees.
An angular fisheye view is defined such that distance from the center of
the image is proportional to the angle from the central view direction.
An angular fisheye can display a full 360 degrees.
A planisphere fisheye view maintains angular relationships between lines,
and is commonly used for sun path analysis.
This is more commonly known as a
"stereographic projection," but we avoid the term here so as not to
confuse it with a stereoscopic pair.
A planisphere fisheye can display up to (but not including) 360 degrees,
although distortion becomes extreme as this limit is approached.
Note that there is no space between the view type
option and its single letter argument.
.TP
.BI -vp " x y z"
Set the view point to
.I "x y z".
This is the focal point of a perspective view or the
center of a parallel projection.
.TP
.BI -vd " xd yd zd"
Set the view direction vector to
.I "xd yd zd".
.TP
.BI -vu " xd yd zd"
Set the view up vector (vertical direction) to
.I "xd yd zd".
.TP
.BI -vh \ val
Set the view horizontal size to
.I val.
For a perspective projection (including fisheye views),
.I val
is the horizontal field of view (in degrees).
For a parallel projection,
.I val
is the view width in world coordinates.
.TP
.BI -vv \ val
Set the view vertical size to
.I val.
.TP
.BI -vo \ val
Set the view fore clipping plane at a distance of
.I val
from the view point.
The plane will be perpendicular to the view direction for
perspective and parallel view types.
For fisheye view types, the clipping plane is actually a clipping
sphere, centered on the view point with radius
.I val.
Objects in front of this imaginary surface will not be visible.
This may be useful for seeing through walls (to get a longer
perspective from an exterior view point) or for incremental
rendering.
A value of zero implies no foreground clipping.
A negative value produces some interesting effects, since it creates an
inverted image for objects behind the viewpoint.
This possibility is provided mostly for the purpose of rendering
stereographic holograms.
.TP
.BI -va \ val
Set the view aft clipping plane at a distance of
.I val
from the view point.
Like the view fore plane, it will be perpendicular to the view
direction for perspective and parallel view types.
For fisheye view types, the clipping plane is actually a clipping
sphere, centered on the view point with radius
.I val.
Objects behind this imaginary surface will not be visible.
A value of zero means no aft clipping, and is the only way to see
infinitely distant objects such as the sky.
.TP
.BI -vs \ val
Set the view shift to
.I val.
This is the amount the actual image will be shifted to the right of
the specified view.
This is option is useful for generating skewed perspectives or
rendering an image a piece at a time.
A value of 1 means that the rendered image starts just to the right of
the normal view.
A value of \-1 would be to the left.
Larger or fractional values are permitted as well.
.TP
.BI -vl \ val
Set the view lift to
.I val.
This is the amount the actual image will be lifted up from the
specified view, similar to the
.I \-vs
option.
.TP
.BI -vf \ file
Get view parameters from
.I file,
which may be a picture or a file created by rvu (with the "view" command).
.TP
.BI -S \ seqstart
Instead of generating a single picture based only on the view
parameters given on the command line, this option causes
.I rhpict
to read view options from the standard input and for each line
containing a valid view specification, generate a corresponding
picture.
.I Seqstart
is a positive integer that will be associated with the first output
frame, and incremented for successive output frames.
By default, each frame is concatenated to the output stream, but it
is possible to change this action using the
.I \-o
option (described below).
Multiple frames may be later extracted from a single output stream using the
.I ra_rgbe(1)
command.
.TP
.BI -o \ fspec
Send the picture(s) to the file(s) given by
.I fspec
instead of the standard output.
If this option is used in combination with
.I \-S
and
.I fspec
contains an integer field for
.I printf(3)
(eg., "%03d") then the actual output file name will include
the current frame number.
.TP
.BR \-w
Turn off warning messages.
.SH EXAMPLE
rhpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.hdk > scene.hdr
.PP
rpict \-S 1 \-o frame%02d.hdr scene.hdk < keyframes.vf
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), pfilt(1), pinterp(1),
printf(3), ra_rgbe(1), rholo(1), rpict(1), rvu(1)
